home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / serus221.zip / SERIOUS.DOC < prev    next >
Text File  |  1990-09-01  |  17KB  |  445 lines
  1.  
  2.                                                                    page 1
  3.  
  4.  
  5.  
  6.  
  7.  
  8.               ----------- SERIOUS Users Guide -----------
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.        SERIOUS version 2.21 -- serial communications device driver
  20.        Copyright (c) 1989,1990 by  Norman J. Goldstein
  21.                                    132 Powell Street
  22.                                    Vancouver BC
  23.                                    Canada  V6A 1G1
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.        This software is distributed under the Shareware concept.
  35.  
  36.        - You are encouraged to copy and distribute the file  SERUS221.ZIP ;
  37.          in its original, unmodified form only.
  38.  
  39.        - No fee is to be charged for the software, other than the actual
  40.          cost of copying and distribution.
  41.  
  42.        - If you end up using  SERIOUS , on other than an evaluation basis,
  43.          you are obliged to send in a registration fee to the copyright owner.
  44.          The last section of this document has details on this.
  45.  
  46.        The copyright owner is not liable for damages of any kind resulting
  47.        from the use of this software.
  48.  
  49.                                                                    page 2
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.                        Contents
  57.  
  58.  
  59.  
  60.        Section                                  Page
  61.  
  62.           1     Introduction                      3
  63.  
  64.           2     How  SERIOUS  works               3
  65.  
  66.           3     Function specifications           4
  67.  
  68.           4     Obtaining the entry address       7
  69.  
  70.           5     The inner workings                8
  71.  
  72.           6     Revisions (future and past)       8
  73.  
  74.           7     Registration                      9
  75.  
  76.  
  77.  
  78.                                                                    page 3
  79.  
  80.        Section 1 -- Introduction
  81.  
  82.        SERIOUS is a device driver for the serial port of the IBM PC and
  83.        compatible computers.  It is not a communications program.  It
  84.        does provide the tools to write your own communications program.
  85.        There are, of course,  BIOS and DOS routines for serial com-
  86.        munications, but these are weak, and are not used in serious
  87.        programs.  The  SERIOUS  device driver is intended to fill this
  88.        gap.
  89.  
  90.  
  91.        Section 2 -- How  SERIOUS  works.
  92.  
  93.        The program is a DOS installable device driver.  The syntax for its
  94.        entry in the config.sys file is
  95.  
  96.        device=serious.sys  [name]  [ord]
  97.  
  98.        The 2 parameters  name  and  ord  are optional, and may be placed
  99.        in any order, separated by at least 1 space.
  100.  
  101.        name -- This is the file name by which DOS will recognize the
  102.                installed driver.  The default name is  SERIOUS0 . The 1st
  103.                character must not be a digit.  Otherwise, the usual DOS
  104.                file naming conventions apply; in particular, the name must
  105.                be at most 8 characters.
  106.  
  107.        ord -- The driver may be configured to contain a buffer in
  108.               which to place incoming characters.  The default is that
  109.               there be no such buffer.  If  ord  is a number between
  110.               1 and 16 , then the driver will contain such a buffer.
  111.               Function 0 (open) of section 3  explains how users may
  112.               supply their own buffer for the driver to use.
  113.  
  114.               The buffer has length  2  to the power of the order.  The
  115.               highest allowable order is  16 , which would give the buffer
  116.               the size of a complete segment -- 64K bytes. The smallest
  117.               allowable order is  1 , creating a meagre  2  byte buffer.
  118.  
  119.               Two advantages to creating and using a default buffer within
  120.               the driver are 1) Less work to later open and use the driver,
  121.               and 2) The buffer remains in RAM even if the application
  122.               program is terminated; this is a convenient way for the driver
  123.               to be reaccessed without any incoming characters having been
  124.               lost, assuming that the terminated program did not close
  125.               the driver.
  126.  
  127.               The disadvantage to creating a default buffer within the
  128.               driver is that it may not be deallocated.  The driver
  129.               code occupies less than  1300  bytes in RAM; having a 2K
  130.               buffer would more than double the RAM being used.
  131.  
  132.  
  133.        The driver contains 5 functions, which may be accessed by the
  134.        applications program.  They are described in the next section.
  135.  
  136.  
  137.                                                                    page 4
  138.  
  139.        Section 3 -- Function specifications
  140.  
  141.        The functions are accessed by the application filling CPU registers
  142.        with appropriate values, and then performing a far call to the
  143.        entry address of  SERIOUS .  The way to obtain the entry address
  144.        is explained in section 4 .  Examples are in the file  serface.c ,
  145.        which contains routines for interfacing with  Turbo C .  These
  146.        examples also illustrate how to construct an assembler interface
  147.        to  SERIOUS .  The file  serdemo.c  is a Turbo C example of an
  148.        application using the interface routines of  serface.c  ; it is a
  149.        dumb terminal.
  150.  
  151.        Every function has the following in common.
  152.  
  153.        Input:   bx = function number.
  154.  
  155.        Returns  bx = error code.
  156.                 A value of  0  indicates no error.
  157.  
  158.        The file  serface.h  defines the numeric values of
  159.        all the error codes.
  160.  
  161.        ------------------------------------------------------------------
  162.        Function 0: Open
  163.  
  164.        Purpose: Inform the driver of the user's configuration, and set up
  165.                 the hardware interrupt routines.
  166.  
  167.        Input:   bx = 0 .
  168.                 ax = base port number of the serial chip.
  169.                 ch = interrupt request number (IRQ) of the serial chip.
  170.  
  171.                 cl = order of the user supplied input buffer.
  172.                 es = segment of the user supplied input buffer.
  173.                 di = offset of the user supplied input buffer.
  174.  
  175.           The 'order' and purpose of the input buffer is described in
  176.           section 2 . A reasonable order is  10 , for a buffer of  1K .
  177.           At  1200 baud, a continuous input stream from the serial port would
  178.           fill up a  1K  buffer in about 10 seconds.  A special case is
  179.           entering a value of  0  for the order.  This informs the driver to
  180.           use the default buffer, which is contained within the driver.  The
  181.           size of this default buffer is determined at installation as a
  182.           command paramater in the config.sys file, as explained in section 2 .
  183.  
  184.           If  port  is specified as  0 , then this function  merely reports
  185.           whether the driver is currnetly open.  No other input information
  186.           is used, in this case.
  187.  
  188.        Return errors: ERR_Active   - driver was already open.
  189.                       ERR_BadOrder - the  order  is not in the allowable
  190.                                      range of between  1  and  16 , or
  191.                       neither a default nor a user-defined buffer was
  192.                       specified.
  193.                       ERR_BadIrq    - The Interrupt Request number is
  194.                                       not between  0  and  15 .
  195.                       ERR_NotActive - this is possible, if  port  is
  196.                                       specified as  0 .
  197.        ------------------------------------------------------------------
  198.  
  199.                                                                    page 5
  200.  
  201.        ------------------------------------------------------------------
  202.        Function 1: SetParms
  203.  
  204.        Purpose: Set the transmission parameters.
  205.  
  206.        Input:   bx = 1 .
  207.                 ax = baud.
  208.                 ch = stop , cl = data.
  209.                 dx = parity.
  210.  
  211.          baud = rate of transmission, between  2  and  65,535
  212.                 bits/second.  Some common values are  300 , 1200  and
  213.                 2400 .  The driver has been tested at  9600 , using a
  214.                 hardwire connection to a